home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 376-400 / disk_388 / free / free.doc < prev    next >
Text File  |  1992-05-06  |  7KB  |  224 lines
  1. FREE:        Display free space on your mounted disk volumes.
  2.  
  3. Author:        Daniel Jay Barrett, barrett@cs.jhu.edu.
  4.         April, 1990.
  5.         Inspired by "Free" by Tom Smythe on Fish Disk 66.
  6.         For a list of improvements over Smythe's program,
  7.          see the end of this file.
  8.  
  9. Distribution:    This program is Freely Distributable.
  10.         Make as many copies as you want.
  11.         Give this program to anybody, without cost.
  12.         Use my source code in any programs of your own.
  13.         (Please give me credit in your program -- thanks!)
  14.  
  15.  
  16.     ----------------------------------------------------------------
  17.  
  18. INTRODUCTION
  19. ------------
  20.  
  21.     This program will display how much free space is remaining
  22. on your disk volumes.  It runs from the CLI only.  The syntax is:
  23.  
  24.     1>  Free [<OPTIONS>] [volume1] [volume2] ... [volumeN]
  25.  
  26.  
  27. HOW TO USE "Free"
  28. ------------------
  29.  
  30. There are three different ways that Free may behave.
  31.  
  32. (1)    You can specify volume names on the command line.  Free will
  33.     display the free space on those volumes only.
  34.  
  35.     Example:
  36.  
  37.         1>  Free df0: df1: RAM:
  38.  
  39.     Of course, you can use the Commodore Shell (or similar shell) to
  40.     define aliases, if you want to see disk space on your favorite
  41.     volumes:
  42.  
  43.         1>  alias floppies Free df0: df1:
  44.         1>  floppies
  45.  
  46. (2)    If you specify NO volume names on the command line, Free will then
  47.     look for an environment variable called FREE_DRIVES.  This is a
  48.     standard Commodore ENV: variable, whose value is set using the
  49.     "setenv" command.
  50.  
  51.     The value of FREE_DRIVES is a list of volumes, separated by
  52.     commas.  There is no whitespace between volumes and commas,
  53.     and each volume must end (as usual) with a colon.  For
  54.     example:
  55.  
  56.         1>  setenv FREE_DRIVES "df0:,df1:,dh0:,dh1:,RAM:,RAD:"
  57.  
  58.     You can put a line like this in your startup-sequence.
  59.  
  60.     REMEMBER:  In order to use environment variables and setenv, you
  61.     must have ENV: assigned somewhere.  (Under AmigaDOS 1.4 and up,
  62.     you must explicitly mount ENV:, I think.)  See your Amiga 
  63.     documentation about ENV: and environment variables.
  64.  
  65. (3)    If you specify no volume names on the command line, and the
  66.     variable FREE_DRIVES does not exist, then Free will use a
  67.     default list of volumes:
  68.  
  69.         RAD:
  70.         DF0:
  71.         DF1:
  72.  
  73.     You can change this default list by modifying the value of
  74.     DEFAULT_VOLUMES in the header file of the source code.
  75.     I see no reason to do this, however, since you can use FREE_DRIVES
  76.     or Shell aliases (adding command-line arguments) to make an
  77.     equivalent change without recompiling.
  78.  
  79.  
  80. GETTING HELP
  81. ------------
  82.  
  83. Type:
  84.         1>  Free ?
  85.  
  86. for a summary of usage information.
  87.  
  88.  
  89. DISPLAYING FREE MEMORY
  90. ----------------------
  91.  
  92.     If you give the volume name "RAM:" (case doesn't matter), you will
  93. be shown how much free memory you have.  If you have FAST RAM, the number
  94. will be broken up into separate CHIP and FAST amounts, plus a TOTAL.
  95.  
  96. COMMAND-LINE OPTIONS
  97. --------------------
  98.  
  99.     Command-line options always begin with a dash '-'.  You may specify
  100. each option with its own dash, or group several options under each dash.
  101. However, all options must preceed all volume names on the command line.
  102.  
  103.     -b    Give answers in blocks instead of bytes.
  104.  
  105.     -r    Turn on volume requestors (turned off by default).
  106.  
  107.         NOTE:  If you use -r and "ENV:" is not available, you
  108.         will get a requestor asking for ENV:.  This is not a
  109.         bug... but I wanted you to be aware of it.  It's a VERY
  110.         good idea ALWAYS to have ENV: available, since more and
  111.         more programs are going to use it.
  112.  
  113.     -m    [Advanced.]  Allocate memory for the output of Free.
  114.         To speed up screen output, everything is stored in a single
  115.         character array and then written to the screen.
  116.         The default array length is BUFSIZ (1024) bytes.
  117.         You can override this number with "-m BYTES", where BYTES
  118.         is the size of the output array.
  119.  
  120.         I doubt you will ever need to use the -m option, but I
  121.         have included it for completeness.
  122.  
  123.     -l    Specify the maximum length of a volume name (including
  124.         the colon).  Free assumes that all your volume names are
  125.         four characters long (df1:, rad:, etc.) or less.
  126.         Use this option to override this default.
  127.  
  128.         The value you specify must be between 1 and 255, inclusive.
  129.  
  130.     Examples:
  131.  
  132.         1>  Free -r -b dh0:
  133.         1>  Free -br df1: df2:
  134.         1>  Free -m 10000 -rbl 8 df1:
  135.         1>  Free -m10000 -bl8
  136.  
  137.  
  138. ERROR HANDLING
  139. --------------
  140.  
  141.     If you specify a volume name illegally, Free will complain about
  142. it.  For example:
  143.  
  144.         1>  Free df1
  145.  
  146. Since "df1" does not end with a colon (should be df1:), it is not a valid 
  147. volume name.
  148.  
  149.     If you specify a legal volume name, but the volume is not mounted,
  150. then Free will display the volume name with the symbol "--" next to it.
  151. This indicates that a floppy drive has no disk in it, or that a volume is
  152. not mounted.
  153.  
  154.     Example:
  155.  
  156.         1>  Free Nonexistent:
  157.         Nonexistent:     --
  158.  
  159.     Non-existent volumes will not cause any volume requestors to pop up,
  160. since Free turns them off while it runs.  (You can enable volume requestors
  161. with the -r option.)
  162.  
  163.  
  164. LIMITATIONS OF THIS PROGRAM
  165. ---------------------------
  166.  
  167.     The following is a list of limitations on how this program
  168. works, due to the way it was designed.  If you don't like these decisions
  169. that I made, just modify the source code and recompile.  (Honestly, these
  170. are such minor issues that I think nobody will care about them.)
  171.  
  172. 1)    If you specify your volume names using FREE_DRIVES, no device
  173.     name may have a comma in it.  The comma is used as a delimiter
  174.     character for separating volume names.
  175.  
  176.     However, this is a simple problem to get around.  You can ASSIGN
  177.     an alternate name for your volume, or you can specify the volume
  178.     on the command line (where there are no "comma" restrictions).
  179.  
  180. 2)    The "free space" displayed must fit into 10 digits, or else
  181.     the indenting may not be correct.  (You don't have to worry about
  182.     this, unless you have more than 10 Gigabytes of space on a volume!)
  183.  
  184.     If you want to change this limit in the source code, just change
  185.     the value of DEFAULT_SPACING in the file free.h.
  186.  
  187. 3)    The length of the value of FREE_DRIVES must be 1023 characters or
  188.     less, or else FREE_DRIVES will be ignored.  I think this is enough
  189.     space.
  190.  
  191.     You can increase this limit in the source code; change the size of 
  192.     array envString in function TheEnvValue() in file env.c.
  193.  
  194. 4)    Free RAM: space is always in bytes, even if the -b option is
  195.     specified.  "Blocks" makes no sense when you're talking about
  196.     RAM:.
  197.  
  198.  
  199. CHANGES/IMPROVEMENTS OVER TOM SMYTHE'S PROGRAM
  200. ----------------------------------------------
  201.  
  202. o    Does not use self-modifying code, so it should work on
  203.     ALL Amigas, not just 68000-based systems.
  204. o    You can specify a device list on the command line.
  205. o    You can specify a device list using an environment variable.
  206. o    Requestors are turned off, so non-mounted devices are just
  207.     skipped.  (See -r option.)
  208. o    Data is written in correct columns, regardless of the 
  209.     lengths of the volume names.  (See -l option.)
  210. o    Total memory free is shown, along with CHIP and FAST
  211.     subtotals.
  212. o    Command-line options added so the user can customize the
  213.     program.
  214. o    Written in ANSI C, in a modular and easy-to-read style.
  215.  
  216.  
  217. STUPID DISCLAIMER
  218. -----------------
  219.  
  220. Daniel Jay Barrett makes no claims about the suitability of this program
  221. for any particular purpose.  Any damages incurred through the use of
  222. this program are entirely the responsibility of the USER.  Use at your
  223. own risk.  So there!   :-)
  224.